feat(stream): add natural time units support for PERIOD trigger by JinqingKuang · Pull Request #34766 · taosdata/TDengine

JinqingKuang · 2026-03-13T02:04:31Z

Description

Implement week/month/year units for stream PERIOD trigger with natural boundary alignment and offset support.

Key changes:

Parser: Add validation for natural time units (w/n/y) and offset parameter
Time utilities: Add getDuration() support for week/month/year units
TriggerTask: Implement window calculation with natural boundary alignment
- Week: align to Monday 00:00:00
- Month: align to 1st of month 00:00:00
- Year: align to Jan 1st 00:00:00
Add offset support: PERIOD(1w, 1d) shifts window by 1 day
Unit tests: Parser validation, time utilities, TriggerTask window calculation
System tests: End-to-end tests for week/month/year units with offset
Documentation: Update user manual with natural time unit examples

Issue(s)

Feat: https://project.feishu.cn/taosdata_td/feature/detail/6490755304

Checklist

Please check the items in the checklist if applicable.

Is the user manual updated?
Are the test cases passed and automated?
Is there no significant decrease in test coverage?

gemini-code-assist · 2026-03-13T02:05:05Z

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the stream processing capabilities by introducing natural time units (weeks, months, years) for PERIOD triggers. This allows users to define stream processing intervals that naturally align with calendar cycles, such as weekly reports or monthly aggregations, with flexible offset options. The changes ensure robust validation and correct behavior across various time precisions and timezone considerations, making scheduled data analysis more powerful and user-friendly.

Highlights

Natural Time Units for PERIOD Trigger: Introduced support for 'week' (w), 'month' (n), and 'year' (y) as time units in the PERIOD trigger for stream processing, allowing for more intuitive and calendar-aligned scheduling.
Natural Boundary Alignment: Implemented logic to align PERIOD triggers with natural boundaries: Monday 00:00:00 for weeks, the 1st of the month 00:00:00 for months, and January 1st 00:00:00 for years. This includes handling multi-period alignment (e.g., bi-weekly, quarterly).
Offset Support for Natural Units: Added functionality to specify an offset_time with natural time units, enabling triggers to shift from their natural boundary (e.g., PERIOD(1w, 1d) to trigger on Tuesday instead of Monday).
Enhanced Validation: Implemented comprehensive validation for the new natural time units and their offsets, including range checks for period values and strict rules for offset units and values (e.g., offset must be strictly less than the period, and month offsets are validated against 28 days/month).
Documentation and Testing: Updated user manuals (English and Chinese) with examples for natural time units and offsets, and added extensive unit and system tests to ensure correctness, performance, and robustness of the new features.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

docs/en/14-reference/03-taos-sql/41-stream.md
- Updated documentation to include PERIOD trigger support for week, month, and year units, along with new examples and offset details.
docs/zh/14-reference/03-taos-sql/41-stream.md
- Updated Chinese documentation to include PERIOD trigger support for week, month, and year units, along with new examples and offset details.
include/common/ttime.h
- Added a new function declaration for alignToNaturalBoundary to support calendar-based time alignment.
include/util/taoserror.h
- Defined new error codes for invalid offset units, invalid offset values, and stream metadata incompatibility.
include/util/tringbuf.h
- Introduced TRingBufGeneral typedef and updated tringbufExtend and tringbufPushBatch to use it for generic ring buffer operations.
source/common/src/msg/streamMsg.c
- Modified stream trigger message encoding and decoding to include period unit, offset unit, and precision.
source/common/src/ttime.c
- Implemented alignToNaturalBoundary for aligning timestamps to natural calendar boundaries (week, month, year) with offset support, and extended getDuration to handle 'w' unit.
source/common/test/CMakeLists.txt
- Added a new test executable ttimeNaturalUnitsTest and included it in the test suite.
source/common/test/ttimeNaturalUnitsTest.cpp
- Added comprehensive unit tests for alignToNaturalBoundary and getDuration functions, covering various natural time units, multi-period alignment, offsets, and precision.
source/libs/new-stream/inc/streamTriggerTask.h
- Added declarations for stTriggerTaskGetTimeWindow, stTriggerTaskPrevTimeWindow, and stTriggerTaskNextTimeWindow to manage stream trigger time windows.
source/libs/new-stream/src/streamTriggerTask.c
- Modified time window calculation and advancement logic to incorporate natural time unit alignment and handle variable-length periods like months and years.
source/libs/new-stream/test/CMakeLists.txt
- Added a new test executable streamTriggerTaskTest and included it in the test suite.
source/libs/new-stream/test/streamTriggerTaskTest.cpp
- Added unit tests for streamTriggerTask functions, verifying correct window calculation, advancement, and offset application for natural time units.
source/libs/parser/src/parTranslater.c
- Updated checkPeriodWindow to validate new natural time units ('w', 'n', 'y') for PERIOD triggers, enforce range constraints, and implement stricter offset unit and value validation.
source/libs/parser/test/parStreamTest.cpp
- Updated parser tests to include new valid and invalid PERIOD trigger syntax for natural time units and offset validation.
source/util/src/terror.c
- Defined error messages for newly introduced error codes related to invalid offset units, values, and stream metadata.
test/cases/18-StreamProcessing/03-TriggerMode/test_period_natural_units.py
- Added a new system test file to verify the functionality and error handling of PERIOD triggers with natural time units and offsets.
test/ci/cases.task
- Added the new system test test_period_natural_units.py to the CI test execution list.

Activity

The author, JinqingKuang, created this pull request to implement week/month/year units for stream PERIOD triggers with natural boundary alignment and offset support.
The PR description details key changes across parser validation, time utilities, TriggerTask implementation, unit tests, system tests, and documentation.
The checklist in the PR description indicates that the user manual has been updated, test cases have passed and are automated, and there is no significant decrease in test coverage.
An associated Feishu issue, 6490755304, is linked for feature tracking.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces support for natural time units (week, month, year) in the PERIOD trigger for streams, which is a valuable enhancement for usability. The implementation is comprehensive, including updates to the core time alignment logic, parser validation, data serialization, and extensive testing across unit, integration, and system levels. The documentation has also been updated clearly. I have a few suggestions to improve code clarity, robustness, and test hygiene.

source/common/src/ttime.c

source/common/test/ttimeNaturalUnitsTest.cpp

source/libs/new-stream/src/streamTriggerTask.c

test/cases/18-StreamProcessing/03-TriggerMode/test_period_natural_units.py

JinqingKuang · 2026-03-13T10:02:36Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces support for natural time units (week, month, year) for the PERIOD trigger, which is a valuable feature enhancement. The changes are comprehensive, covering documentation, parser validation, core time alignment logic, and message serialization. The addition of extensive unit and end-to-end tests is particularly commendable and ensures the feature's reliability. My review includes one high-severity suggestion to improve the robustness of the time alignment logic by adding error handling and a couple of medium-severity suggestions to enhance the clarity of the user documentation.

source/common/src/ttime.c

docs/en/14-reference/03-taos-sql/41-stream.md

docs/zh/14-reference/03-taos-sql/41-stream.md

Implement week/month/year units for stream PERIOD trigger with natural boundary alignment and offset support. Key changes: - Parser: Add validation for natural time units (w/n/y) and offset parameter - Time utilities: Add getDuration() support for week/month/year units - TriggerTask: Implement window calculation with natural boundary alignment - Week: align to Monday 00:00:00 - Month: align to 1st of month 00:00:00 - Year: align to Jan 1st 00:00:00 - Add offset support: PERIOD(1w, 1d) shifts window by 1 day - Unit tests: Parser validation, time utilities, TriggerTask window calculation - System tests: End-to-end tests for week/month/year units with offset - Documentation: Update user manual with natural time unit examples Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Adds support for natural calendar units (week/month/year) to stream PERIOD triggers, including natural boundary alignment and an optional offset, and wires the new metadata through parser/runtime plus tests/docs.

Changes:

Extend PERIOD parsing/validation to accept w/n/y units and validate offset < period (with month validation based on 28 days).
Implement natural-boundary alignment in time utilities and trigger-task window calculation for week/month/year (+ offset).
Add unit/system tests and update user docs + error codes for new validation errors.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
test/ci/cases.task	Adds CI entry for the new PERIOD natural units system test.
test/cases/18-StreamProcessing/20-UseCase/tobacco_data/idmp/stream.json	Adjusts an existing PERIOD offset to satisfy stricter validation.
test/cases/18-StreamProcessing/03-TriggerMode/test_period_natural_units.py	New system test coverage for `w/n/y` PERIOD units and offsets.
source/util/src/terror.c	Adds error strings for invalid offset unit/value.
include/util/taoserror.h	Adds new parser error codes for offset validation.
docs/en/14-reference/09-error-code.md	Documents new error codes (EN).
docs/zh/14-reference/09-error-code.md	Documents new error codes (ZH).
source/libs/parser/src/parTranslater.c	Parser-side PERIOD unit/range + offset validation logic updates.
source/libs/parser/test/parStreamTest.cpp	Adds/updates parser tests for PERIOD ranges and offsets.
include/common/ttime.h	Exposes `alignToNaturalBoundary()` API.
source/common/src/ttime.c	Implements `alignToNaturalBoundary()` and adds `getDuration()` support for week.
source/common/test/ttimeNaturalUnitsTest.cpp	Adds unit tests for natural boundary alignment + duration conversion.
source/common/test/CMakeLists.txt	Registers the new common unit test binary.
source/libs/new-stream/src/streamTriggerTask.c	Implements natural-unit window calculation + exports helper functions.
source/libs/new-stream/inc/streamTriggerTask.h	Exposes trigger-task window helper functions for testing/usage.
source/libs/new-stream/test/streamTriggerTaskTest.cpp	Adds trigger-task window unit tests for natural units/offsets.
source/libs/new-stream/test/CMakeLists.txt	Adds the new new-stream unit test target.
source/common/src/msg/streamMsg.c	Extends stream trigger deploy message encoding/decoding for PERIOD metadata.
include/util/tringbuf.h	Refactors internal ring buffer type aliasing/casts for general use.
docs/en/14-reference/03-taos-sql/41-stream.md	Updates PERIOD docs with natural unit behavior/examples (EN).
docs/zh/14-reference/03-taos-sql/41-stream.md	Updates PERIOD docs with natural unit behavior/examples (ZH).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

source/common/test/ttimeNaturalUnitsTest.cpp

docs/en/14-reference/03-taos-sql/41-stream.md

docs/zh/14-reference/03-taos-sql/41-stream.md

source/common/src/msg/streamMsg.c

source/common/src/ttime.c

source/libs/new-stream/src/streamTriggerTask.c

source/common/test/ttimeNaturalUnitsTest.cpp

JinqingKuang requested review from dapan1121, guanshengliang, hzcheng and zitsen as code owners March 13, 2026 02:04

Copilot AI review requested due to automatic review settings March 13, 2026 02:04

JinqingKuang requested a review from a team as a code owner March 13, 2026 02:04

taosdata-bot bot added the team engine label Mar 13, 2026

Copilot started reviewing on behalf of JinqingKuang March 13, 2026 02:05 View session

gemini-code-assist bot reviewed Mar 13, 2026

View reviewed changes

This comment was marked as outdated.

Sign in to view

JinqingKuang force-pushed the feat/stream-natural-time-units branch from 9d70529 to c1eb39e Compare March 13, 2026 03:03

Copilot AI review requested due to automatic review settings March 13, 2026 06:49

JinqingKuang force-pushed the feat/stream-natural-time-units branch from c1eb39e to fca9717 Compare March 13, 2026 06:49

Copilot started reviewing on behalf of JinqingKuang March 13, 2026 06:50 View session

This comment was marked as outdated.

Sign in to view

Copilot AI review requested due to automatic review settings March 13, 2026 09:13

Copilot started reviewing on behalf of JinqingKuang March 13, 2026 09:14 View session

This comment was marked as outdated.

Sign in to view

JinqingKuang force-pushed the feat/stream-natural-time-units branch from e5f65db to b4fe192 Compare March 13, 2026 09:52

JinqingKuang requested a review from Copilot March 13, 2026 10:02

Copilot started reviewing on behalf of JinqingKuang March 13, 2026 10:02 View session

gemini-code-assist bot reviewed Mar 13, 2026

View reviewed changes

source/common/src/ttime.c Show resolved Hide resolved

docs/en/14-reference/03-taos-sql/41-stream.md Show resolved Hide resolved

docs/zh/14-reference/03-taos-sql/41-stream.md Show resolved Hide resolved

This comment was marked as outdated.

Sign in to view

JinqingKuang force-pushed the feat/stream-natural-time-units branch from b4fe192 to 4552305 Compare March 14, 2026 02:42

Copilot AI review requested due to automatic review settings March 14, 2026 03:02

JinqingKuang force-pushed the feat/stream-natural-time-units branch from 4552305 to a25590f Compare March 14, 2026 03:02

Copilot started reviewing on behalf of JinqingKuang March 14, 2026 03:02 View session

Copilot AI reviewed Mar 14, 2026

View reviewed changes

Conversation

JinqingKuang commented Mar 13, 2026

Description

Issue(s)

Checklist

Uh oh!

gemini-code-assist bot commented Mar 13, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

JinqingKuang commented Mar 13, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants